home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / include / libpurple / account.h next >
Encoding:
C/C++ Source or Header  |  2007-05-04  |  28.1 KB  |  974 lines
  1. /**
  2.  * @file account.h Account API
  3.  * @ingroup core
  4.  *
  5.  * purple
  6.  *
  7.  * Purple is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  *
  25.  * @see @ref account-signals
  26.  */
  27. #ifndef _PURPLE_ACCOUNT_H_
  28. #define _PURPLE_ACCOUNT_H_
  29.  
  30. #include <glib-object.h>
  31. #include <glib.h>
  32. #include <glib-object.h>
  33.  
  34. typedef struct _PurpleAccountUiOps PurpleAccountUiOps;
  35. typedef struct _PurpleAccount      PurpleAccount;
  36.  
  37. typedef gboolean (*PurpleFilterAccountFunc)(PurpleAccount *account);
  38. typedef void (*PurpleAccountRequestAuthorizationCb)(void *);
  39.  
  40. #include "connection.h"
  41. #include "log.h"
  42. #include "proxy.h"
  43. #include "prpl.h"
  44. #include "status.h"
  45.  
  46. /**
  47.  * Account request types.
  48.  */
  49. typedef enum
  50. {
  51.     PURPLE_ACCOUNT_REQUEST_AUTHORIZATION = 0 /* Account authorization request */
  52. } PurpleAccountRequestType;
  53.  
  54. struct _PurpleAccountUiOps
  55. {
  56.     /* A buddy we already have added us to their buddy list. */
  57.     void (*notify_added)(PurpleAccount *account, const char *remote_user,
  58.                         const char *id, const char *alias,
  59.                          const char *message);
  60.     void (*status_changed)(PurpleAccount *account, PurpleStatus *status);
  61.     /* Someone we don't have on our list added us. Will prompt to add them. */
  62.     void (*request_add)(PurpleAccount *account, const char *remote_user,
  63.                         const char *id, const char *alias,
  64.                         const char *message);
  65.     void *(*request_authorize)(PurpleAccount *account, const char *remote_user, const char *id,
  66.                  const char *alias, const char *message, gboolean on_list, 
  67.                  GCallback authorize_cb, GCallback deny_cb, void *user_data);
  68.     void (*close_account_request)(void *ui_handle);
  69.  
  70.     void (*_purple_reserved1)(void);
  71.     void (*_purple_reserved2)(void);
  72.     void (*_purple_reserved3)(void);
  73.     void (*_purple_reserved4)(void);
  74. };
  75.  
  76. struct _PurpleAccount
  77. {
  78.     char *username;             /**< The username.                          */
  79.     char *alias;                /**< How you appear to yourself.            */
  80.     char *password;             /**< The account password.                  */
  81.     char *user_info;            /**< User information.                      */
  82.  
  83.     char *buddy_icon_path;      /**< The buddy icon's non-cached path.      */
  84.  
  85.     gboolean remember_pass;     /**< Remember the password.                 */
  86.  
  87.     char *protocol_id;          /**< The ID of the protocol.                */
  88.  
  89.     PurpleConnection *gc;         /**< The connection handle.                 */
  90.     gboolean disconnecting;     /**< The account is currently disconnecting */
  91.  
  92.     GHashTable *settings;       /**< Protocol-specific settings.            */
  93.     GHashTable *ui_settings;    /**< UI-specific settings.                  */
  94.  
  95.     PurpleProxyInfo *proxy_info;  /**< Proxy information.  This will be set   */
  96.                                 /*   to NULL when the account inherits      */
  97.                                 /*   proxy settings from global prefs.      */
  98.  
  99.     GSList *permit;             /**< Permit list.                           */
  100.     GSList *deny;               /**< Deny list.                             */
  101.     int perm_deny;              /**< The permit/deny setting.               */
  102.  
  103.     GList *status_types;        /**< Status types.                          */
  104.  
  105.     PurplePresence *presence;     /**< Presence.                              */
  106.     PurpleLog *system_log;        /**< The system log                         */
  107.  
  108.     void *ui_data;              /**< The UI can put data here.              */
  109. };
  110.  
  111. #ifdef __cplusplus
  112. extern "C" {
  113. #endif
  114.  
  115. /**************************************************************************/
  116. /** @name Account API                                                     */
  117. /**************************************************************************/
  118. /*@{*/
  119.  
  120. /**
  121.  * Creates a new account.
  122.  *
  123.  * @param username    The username.
  124.  * @param protocol_id The protocol ID.
  125.  *
  126.  * @return The new account.
  127.  */
  128. PurpleAccount *purple_account_new(const char *username, const char *protocol_id);
  129.  
  130. /**
  131.  * Destroys an account.
  132.  *
  133.  * @param account The account to destroy.
  134.  */
  135. void purple_account_destroy(PurpleAccount *account);
  136.  
  137. /**
  138.  * Connects to an account.
  139.  *
  140.  * @param account The account to connect to.
  141.  */
  142. void purple_account_connect(PurpleAccount *account);
  143.  
  144. /**
  145.  * Registers an account.
  146.  *
  147.  * @param account The account to register.
  148.  */
  149. void purple_account_register(PurpleAccount *account);
  150.  
  151. /**
  152.  * Disconnects from an account.
  153.  *
  154.  * @param account The account to disconnect from.
  155.  */
  156. void purple_account_disconnect(PurpleAccount *account);
  157.  
  158. /**
  159.  * Notifies the user that the account was added to a remote user's
  160.  * buddy list.
  161.  *
  162.  * This will present a dialog informing the user that he was added to the
  163.  * remote user's buddy list.
  164.  *
  165.  * @param account     The account that was added.
  166.  * @param remote_user The name of the user that added this account.
  167.  * @param id          The optional ID of the local account. Rarely used.
  168.  * @param alias       The optional alias of the user.
  169.  * @param message     The optional message sent from the user adding you.
  170.  */
  171. void purple_account_notify_added(PurpleAccount *account, const char *remote_user,
  172.                                const char *id, const char *alias,
  173.                                const char *message);
  174.  
  175. /**
  176.  * Notifies the user that the account was addded to a remote user's buddy
  177.  * list and asks ther user if they want to add the remote user to their buddy
  178.  * list.
  179.  *
  180.  * This will present a dialog informing the local user that the remote user
  181.  * added them to the remote user's buddy list and will ask if they want to add
  182.  * the remote user to the buddy list.
  183.  *
  184.  * @param account     The account that was added.
  185.  * @param remote_user The name of the user that added this account.
  186.  * @param id          The optional ID of the local account. Rarely used.
  187.  * @param alias       The optional alias of the user.
  188.  * @param message     The optional message sent from the user adding you.
  189.  */
  190. void purple_account_request_add(PurpleAccount *account, const char *remote_user,
  191.                               const char *id, const char *alias,
  192.                               const char *message);
  193.  
  194. /**
  195.  * Notifies the user that a remote user has wants to add the local user
  196.  * to his or her buddy list and requires authorization to d oso.
  197.  *
  198.  * This will present a dialog informing the user of this and ask if the 
  199.  * user authorizes or denies the remote user from adding him.
  200.  *
  201.  * @param account      The account that was added
  202.  * @param remote_user  The name of the user that added this account.
  203.  * @param id           The optional ID of the local account. Rarely used.
  204.  * @param alias        The optional alias of the remote user.
  205.  * @param message      The optional message sent from the uer requesting you
  206.  * @param on_list      Is the remote user already on the buddy list?
  207.  * @param auth_cb      The callback called when the local user accepts
  208.  * @param deny_cb      The callback called when the local user rejects
  209.  * @param user_data    Data to be passed back to the above callbacks
  210.  *
  211.  * @return A UI-specific handle.
  212.  */
  213. void *purple_account_request_authorization(PurpleAccount *account, const char *remote_user,
  214.                     const char *id, const char *alias, const char *message, gboolean on_list,
  215.                     GCallback auth_cb, GCallback deny_cb, void *user_data);
  216.  
  217. /**
  218.  * Close account requests registered for the given PurpleAccount
  219.  *
  220.  * @param account       The account for which requests should be closed
  221.  */
  222. void purple_account_request_close_with_account(PurpleAccount *account);
  223.  
  224. /**
  225.  * Close the account request for the given ui handle
  226.  *
  227.  * @param ui_handle       The ui specific handle for which requests should be closed
  228.  */
  229. void purple_account_request_close(void *ui_handle);
  230.  
  231. /**
  232.  * Requests a password from the user for the account. Does not set the
  233.  * account password on success; do that in ok_cb if desired.
  234.  *
  235.  * @param account     The account to request the password for.
  236.  * @param ok_cb       The callback for the OK button.
  237.  * @param cancel_cb   The callback for the cancel button.
  238.  * @param user_data   User data to be passed into callbacks.
  239.  */
  240. void purple_account_request_password(PurpleAccount *account, GCallback ok_cb,
  241.                      GCallback cancel_cb, void *user_data);
  242.  
  243. /**
  244.  * Requests information from the user to change the account's password.
  245.  *
  246.  * @param account The account to change the password on.
  247.  */
  248. void purple_account_request_change_password(PurpleAccount *account);
  249.  
  250. /**
  251.  * Requests information from the user to change the account's
  252.  * user information.
  253.  *
  254.  * @param account The account to change the user information on.
  255.  */
  256. void purple_account_request_change_user_info(PurpleAccount *account);
  257.  
  258. /**
  259.  * Sets the account's username.
  260.  *
  261.  * @param account  The account.
  262.  * @param username The username.
  263.  */
  264. void purple_account_set_username(PurpleAccount *account, const char *username);
  265.  
  266. /**
  267.  * Sets the account's password.
  268.  *
  269.  * @param account  The account.
  270.  * @param password The password.
  271.  */
  272. void purple_account_set_password(PurpleAccount *account, const char *password);
  273.  
  274. /**
  275.  * Sets the account's alias.
  276.  *
  277.  * @param account The account.
  278.  * @param alias   The alias.
  279.  */
  280. void purple_account_set_alias(PurpleAccount *account, const char *alias);
  281.  
  282. /**
  283.  * Sets the account's user information
  284.  *
  285.  * @param account   The account.
  286.  * @param user_info The user information.
  287.  */
  288. void purple_account_set_user_info(PurpleAccount *account, const char *user_info);
  289.  
  290. /**
  291.  * Sets the account's buddy icon path.
  292.  *
  293.  * @param account The account.
  294.  * @param path      The buddy icon non-cached path.
  295.  */
  296. void purple_account_set_buddy_icon_path(PurpleAccount *account, const char *path);
  297.  
  298. /**
  299.  * Sets the account's protocol ID.
  300.  *
  301.  * @param account     The account.
  302.  * @param protocol_id The protocol ID.
  303.  */
  304. void purple_account_set_protocol_id(PurpleAccount *account,
  305.                                   const char *protocol_id);
  306.  
  307. /**
  308.  * Sets the account's connection.
  309.  *
  310.  * @param account The account.
  311.  * @param gc      The connection.
  312.  */
  313. void purple_account_set_connection(PurpleAccount *account, PurpleConnection *gc);
  314.  
  315. /**
  316.  * Sets whether or not this account should save its password.
  317.  *
  318.  * @param account The account.
  319.  * @param value   @c TRUE if it should remember the password.
  320.  */
  321. void purple_account_set_remember_password(PurpleAccount *account, gboolean value);
  322.  
  323. /**
  324.  * Sets whether or not this account should check for mail.
  325.  *
  326.  * @param account The account.
  327.  * @param value   @c TRUE if it should check for mail.
  328.  */
  329. void purple_account_set_check_mail(PurpleAccount *account, gboolean value);
  330.  
  331. /**
  332.  * Sets whether or not this account is enabled for the specified
  333.  * UI.
  334.  *
  335.  * @param account The account.
  336.  * @param ui      The UI.
  337.  * @param value   @c TRUE if it is enabled.
  338.  */
  339. void purple_account_set_enabled(PurpleAccount *account, const char *ui,
  340.                   gboolean value);
  341.  
  342. /**
  343.  * Sets the account's proxy information.
  344.  *
  345.  * @param account The account.
  346.  * @param info    The proxy information.
  347.  */
  348. void purple_account_set_proxy_info(PurpleAccount *account, PurpleProxyInfo *info);
  349.  
  350. /**
  351.  * Sets the account's status types.
  352.  *
  353.  * @param account      The account.
  354.  * @param status_types The list of status types.
  355.  */
  356. void purple_account_set_status_types(PurpleAccount *account, GList *status_types);
  357.  
  358. /**
  359.  * Activates or deactivates a status.  All changes to the statuses of
  360.  * an account go through this function or purple_account_set_status_list.
  361.  *
  362.  * Only independent statuses can be deactivated with this. To deactivate
  363.  * an exclusive status, activate a different (and exclusive?) status.
  364.  *
  365.  * @param account   The account.
  366.  * @param status_id The ID of the status.
  367.  * @param active    The active state.
  368.  * @param ...       Pairs of attributes for the new status passed in
  369.  *                  as a NULL-terminated list of id/value pairs.
  370.  */
  371. void purple_account_set_status(PurpleAccount *account, const char *status_id,
  372.                              gboolean active, ...);
  373.  
  374.  
  375. /**
  376.  * Activates or deactivates a status.  All changes to the statuses of
  377.  * an account go through this function or purple_account_set_status.
  378.  *
  379.  * Only independent statuses can be deactivated with this. To deactivate
  380.  * an exclusive status, activate a different (and exclusive?) status.
  381.  *
  382.  * @param account   The account.
  383.  * @param status_id The ID of the status.
  384.  * @param active    The active state.
  385.  * @param attrs        A list of attributes in key/value pairs
  386.  */
  387. void purple_account_set_status_list(PurpleAccount *account,
  388.                                   const char *status_id,
  389.                                   gboolean active, GList *attrs);
  390.  
  391. /**
  392.  * Clears all protocol-specific settings on an account.
  393.  *
  394.  * @param account The account.
  395.  */
  396. void purple_account_clear_settings(PurpleAccount *account);
  397.  
  398. /**
  399.  * Sets a protocol-specific integer setting for an account.
  400.  *
  401.  * @param account The account.
  402.  * @param name    The name of the setting.
  403.  * @param value   The setting's value.
  404.  */
  405. void purple_account_set_int(PurpleAccount *account, const char *name, int value);
  406.  
  407. /**
  408.  * Sets a protocol-specific string setting for an account.
  409.  *
  410.  * @param account The account.
  411.  * @param name    The name of the setting.
  412.  * @param value   The setting's value.
  413.  */
  414. void purple_account_set_string(PurpleAccount *account, const char *name,
  415.                              const char *value);
  416.  
  417. /**
  418.  * Sets a protocol-specific boolean setting for an account.
  419.  *
  420.  * @param account The account.
  421.  * @param name    The name of the setting.
  422.  * @param value   The setting's value.
  423.  */
  424. void purple_account_set_bool(PurpleAccount *account, const char *name,
  425.                            gboolean value);
  426.  
  427. /**
  428.  * Sets a UI-specific integer setting for an account.
  429.  *
  430.  * @param account The account.
  431.  * @param ui      The UI name.
  432.  * @param name    The name of the setting.
  433.  * @param value   The setting's value.
  434.  */
  435. void purple_account_set_ui_int(PurpleAccount *account, const char *ui,
  436.                              const char *name, int value);
  437.  
  438. /**
  439.  * Sets a UI-specific string setting for an account.
  440.  *
  441.  * @param account The account.
  442.  * @param ui      The UI name.
  443.  * @param name    The name of the setting.
  444.  * @param value   The setting's value.
  445.  */
  446. void purple_account_set_ui_string(PurpleAccount *account, const char *ui,
  447.                                 const char *name, const char *value);
  448.  
  449. /**
  450.  * Sets a UI-specific boolean setting for an account.
  451.  *
  452.  * @param account The account.
  453.  * @param ui      The UI name.
  454.  * @param name    The name of the setting.
  455.  * @param value   The setting's value.
  456.  */
  457. void purple_account_set_ui_bool(PurpleAccount *account, const char *ui,
  458.                               const char *name, gboolean value);
  459.  
  460. /**
  461.  * Returns whether or not the account is connected.
  462.  *
  463.  * @param account The account.
  464.  *
  465.  * @return @c TRUE if connected, or @c FALSE otherwise.
  466.  */
  467. gboolean purple_account_is_connected(const PurpleAccount *account);
  468.  
  469. /**
  470.  * Returns whether or not the account is connecting.
  471.  *
  472.  * @param account The account.
  473.  *
  474.  * @return @c TRUE if connecting, or @c FALSE otherwise.
  475.  */
  476. gboolean purple_account_is_connecting(const PurpleAccount *account);
  477.  
  478. /**
  479.  * Returns whether or not the account is disconnected.
  480.  *
  481.  * @param account The account.
  482.  *
  483.  * @return @c TRUE if disconnected, or @c FALSE otherwise.
  484.  */
  485. gboolean purple_account_is_disconnected(const PurpleAccount *account);
  486.  
  487. /**
  488.  * Returns the account's username.
  489.  *
  490.  * @param account The account.
  491.  *
  492.  * @return The username.
  493.  */
  494. const char *purple_account_get_username(const PurpleAccount *account);
  495.  
  496. /**
  497.  * Returns the account's password.
  498.  *
  499.  * @param account The account.
  500.  *
  501.  * @return The password.
  502.  */
  503. const char *purple_account_get_password(const PurpleAccount *account);
  504.  
  505. /**
  506.  * Returns the account's alias.
  507.  *
  508.  * @param account The account.
  509.  *
  510.  * @return The alias.
  511.  */
  512. const char *purple_account_get_alias(const PurpleAccount *account);
  513.  
  514. /**
  515.  * Returns the account's user information.
  516.  *
  517.  * @param account The account.
  518.  *
  519.  * @return The user information.
  520.  */
  521. const char *purple_account_get_user_info(const PurpleAccount *account);
  522.  
  523. /**
  524.  * Gets the account's buddy icon path.
  525.  *
  526.  * @param account The account.
  527.  *
  528.  * @return The buddy icon's non-cached path.
  529.  */
  530. const char *purple_account_get_buddy_icon_path(const PurpleAccount *account);
  531.  
  532. /**
  533.  * Returns the account's protocol ID.
  534.  *
  535.  * @param account The account.
  536.  *
  537.  * @return The protocol ID.
  538.  */
  539. const char *purple_account_get_protocol_id(const PurpleAccount *account);
  540.  
  541. /**
  542.  * Returns the account's protocol name.
  543.  *
  544.  * @param account The account.
  545.  *
  546.  * @return The protocol name.
  547.  */
  548. const char *purple_account_get_protocol_name(const PurpleAccount *account);
  549.  
  550. /**
  551.  * Returns the account's connection.
  552.  *
  553.  * @param account The account.
  554.  *
  555.  * @return The connection.
  556.  */
  557. PurpleConnection *purple_account_get_connection(const PurpleAccount *account);
  558.  
  559. /**
  560.  * Returns whether or not this account should save its password.
  561.  *
  562.  * @param account The account.
  563.  *
  564.  * @return @c TRUE if it should remember the password.
  565.  */
  566. gboolean purple_account_get_remember_password(const PurpleAccount *account);
  567.  
  568. /**
  569.  * Returns whether or not this account should check for mail.
  570.  *
  571.  * @param account The account.
  572.  *
  573.  * @return @c TRUE if it should check for mail.
  574.  */
  575. gboolean purple_account_get_check_mail(const PurpleAccount *account);
  576.  
  577. /**
  578.  * Returns whether or not this account is enabled for the
  579.  * specified UI.
  580.  *
  581.  * @param account The account.
  582.  * @param ui      The UI.
  583.  *
  584.  * @return @c TRUE if it enabled on this UI.
  585.  */
  586. gboolean purple_account_get_enabled(const PurpleAccount *account,
  587.                   const char *ui);
  588.  
  589. /**
  590.  * Returns the account's proxy information.
  591.  *
  592.  * @param account The account.
  593.  *
  594.  * @return The proxy information.
  595.  */
  596. PurpleProxyInfo *purple_account_get_proxy_info(const PurpleAccount *account);
  597.  
  598. /**
  599.  * Returns the active status for this account.  This looks through
  600.  * the PurplePresence associated with this account and returns the
  601.  * PurpleStatus that has its active flag set to "TRUE."  There can be
  602.  * only one active PurpleStatus in a PurplePresence.
  603.  *
  604.  * @param account   The account.
  605.  *
  606.  * @return The active status.
  607.  */
  608. PurpleStatus *purple_account_get_active_status(const PurpleAccount *account);
  609.  
  610. /**
  611.  * Returns the account status with the specified ID.
  612.  *
  613.  * Note that this works differently than purple_buddy_get_status() in that
  614.  * it will only return NULL if the status was not registered.
  615.  *
  616.  * @param account   The account.
  617.  * @param status_id The status ID.
  618.  *
  619.  * @return The status, or NULL if it was never registered.
  620.  */
  621. PurpleStatus *purple_account_get_status(const PurpleAccount *account,
  622.                                     const char *status_id);
  623.  
  624. /**
  625.  * Returns the account status type with the specified ID.
  626.  *
  627.  * @param account The account.
  628.  * @param id      The ID of the status type to find.
  629.  *
  630.  * @return The status type if found, or NULL.
  631.  */
  632. PurpleStatusType *purple_account_get_status_type(const PurpleAccount *account,
  633.                                              const char *id);
  634.  
  635. /**
  636.  * Returns the account status type with the specified primitive.
  637.  * Note: It is possible for an account to have more than one
  638.  * PurpleStatusType with the same primitive.  In this case, the
  639.  * first PurpleStatusType is returned.
  640.  *
  641.  * @param account   The account.
  642.  * @param primitive The type of the status type to find.
  643.  *
  644.  * @return The status if found, or NULL.
  645.  */
  646. PurpleStatusType *purple_account_get_status_type_with_primitive(
  647.                             const PurpleAccount *account,
  648.                             PurpleStatusPrimitive primitive);
  649.  
  650. /**
  651.  * Returns the account's presence.
  652.  *
  653.  * @param account The account.
  654.  *
  655.  * @return The account's presence.
  656.  */
  657. PurplePresence *purple_account_get_presence(const PurpleAccount *account);
  658.  
  659. /**
  660.  * Returns whether or not an account status is active.
  661.  *
  662.  * @param account   The account.
  663.  * @param status_id The status ID.
  664.  *
  665.  * @return TRUE if active, or FALSE if not.
  666.  */
  667. gboolean purple_account_is_status_active(const PurpleAccount *account,
  668.                                        const char *status_id);
  669.  
  670. /**
  671.  * Returns the account's status types.
  672.  *
  673.  * @param account The account.
  674.  *
  675.  * @return The account's status types.
  676.  */
  677. const GList *purple_account_get_status_types(const PurpleAccount *account);
  678.  
  679. /**
  680.  * Returns a protocol-specific integer setting for an account.
  681.  *
  682.  * @param account       The account.
  683.  * @param name          The name of the setting.
  684.  * @param default_value The default value.
  685.  *
  686.  * @return The value.
  687.  */
  688. int purple_account_get_int(const PurpleAccount *account, const char *name,
  689.                          int default_value);
  690.  
  691. /**
  692.  * Returns a protocol-specific string setting for an account.
  693.  *
  694.  * @param account       The account.
  695.  * @param name          The name of the setting.
  696.  * @param default_value The default value.
  697.  *
  698.  * @return The value.
  699.  */
  700. const char *purple_account_get_string(const PurpleAccount *account,
  701.                                     const char *name,
  702.                                     const char *default_value);
  703.  
  704. /**
  705.  * Returns a protocol-specific boolean setting for an account.
  706.  *
  707.  * @param account       The account.
  708.  * @param name          The name of the setting.
  709.  * @param default_value The default value.
  710.  *
  711.  * @return The value.
  712.  */
  713. gboolean purple_account_get_bool(const PurpleAccount *account, const char *name,
  714.                                gboolean default_value);
  715.  
  716. /**
  717.  * Returns a UI-specific integer setting for an account.
  718.  *
  719.  * @param account       The account.
  720.  * @param ui            The UI name.
  721.  * @param name          The name of the setting.
  722.  * @param default_value The default value.
  723.  *
  724.  * @return The value.
  725.  */
  726. int purple_account_get_ui_int(const PurpleAccount *account, const char *ui,
  727.                             const char *name, int default_value);
  728.  
  729. /**
  730.  * Returns a UI-specific string setting for an account.
  731.  *
  732.  * @param account       The account.
  733.  * @param ui            The UI name.
  734.  * @param name          The name of the setting.
  735.  * @param default_value The default value.
  736.  *
  737.  * @return The value.
  738.  */
  739. const char *purple_account_get_ui_string(const PurpleAccount *account,
  740.                                        const char *ui, const char *name,
  741.                                        const char *default_value);
  742.  
  743. /**
  744.  * Returns a UI-specific boolean setting for an account.
  745.  *
  746.  * @param account       The account.
  747.  * @param ui            The UI name.
  748.  * @param name          The name of the setting.
  749.  * @param default_value The default value.
  750.  *
  751.  * @return The value.
  752.  */
  753. gboolean purple_account_get_ui_bool(const PurpleAccount *account, const char *ui,
  754.                                   const char *name, gboolean default_value);
  755.  
  756.  
  757. /**
  758.  * Returns the system log for an account.
  759.  *
  760.  * @param account The account.
  761.  * @param create  Should it be created if it doesn't exist?
  762.  *
  763.  * @return The log.
  764.  *
  765.  * @note Callers should almost always pass @c FALSE for @a create.
  766.  *       Passing @c TRUE could result in an existing log being reopened,
  767.  *       if the log has already been closed, which not all loggers deal
  768.  *       with appropriately.
  769.  */
  770. PurpleLog *purple_account_get_log(PurpleAccount *account, gboolean create);
  771.  
  772. /**
  773.  * Frees the system log of an account
  774.  *
  775.  * @param account The account.
  776.  */
  777. void purple_account_destroy_log(PurpleAccount *account);
  778.  
  779. /**
  780.  * Adds a buddy to the server-side buddy list for the specified account.
  781.  *
  782.  * @param account The account.
  783.  * @param buddy The buddy to add.
  784.  */
  785. void purple_account_add_buddy(PurpleAccount *account, PurpleBuddy *buddy);
  786. /**
  787.  * Adds a list of buddies to the server-side buddy list.
  788.  *
  789.  * @param account The account.
  790.  * @param buddies The list of PurpleBlistNodes representing the buddies to add.
  791.  */
  792. void purple_account_add_buddies(PurpleAccount *account, GList *buddies);
  793.  
  794. /**
  795.  * Removes a buddy from the server-side buddy list.
  796.  *
  797.  * @param account The account.
  798.  * @param buddy The buddy to remove.
  799.  * @param group The group to remove the buddy from.
  800.  */
  801. void purple_account_remove_buddy(PurpleAccount *account, PurpleBuddy *buddy,
  802.                                 PurpleGroup *group);
  803.  
  804. /**
  805.  * Removes a list of buddies from the server-side buddy list.
  806.  *
  807.  * @note The lists buddies and groups are parallel lists.  Be sure that node n of
  808.  *       groups matches node n of buddies.
  809.  *
  810.  * @param account The account.
  811.  * @param buddies The list of buddies to remove.
  812.  * @param groups The list of groups to remove buddies from.  Each node of this
  813.  *               list should match the corresponding node of buddies.
  814.  */
  815. void purple_account_remove_buddies(PurpleAccount *account, GList *buddies,
  816.                                     GList *groups);
  817.  
  818. /**
  819.  * Removes a group from the server-side buddy list.
  820.  *
  821.  * @param account The account.
  822.  * @param group The group to remove.
  823.  */
  824. void purple_account_remove_group(PurpleAccount *account, PurpleGroup *group);
  825.  
  826. /**
  827.  * Changes the password on the specified account.
  828.  *
  829.  * @param account The account.
  830.  * @param orig_pw The old password.
  831.  * @param new_pw The new password.
  832.  */
  833. void purple_account_change_password(PurpleAccount *account, const char *orig_pw,
  834.                                     const char *new_pw);
  835.  
  836. /**
  837.  * Whether the account supports sending offline messages to buddy.
  838.  *
  839.  * @param account The account
  840.  * @param buddy   The buddy
  841.  */
  842. gboolean purple_account_supports_offline_message(PurpleAccount *account, PurpleBuddy *buddy);
  843.  
  844. /*@}*/
  845.  
  846. /**************************************************************************/
  847. /** @name Accounts API                                                    */
  848. /**************************************************************************/
  849. /*@{*/
  850.  
  851. /**
  852.  * Adds an account to the list of accounts.
  853.  *
  854.  * @param account The account.
  855.  */
  856. void purple_accounts_add(PurpleAccount *account);
  857.  
  858. /**
  859.  * Removes an account from the list of accounts.
  860.  *
  861.  * @param account The account.
  862.  */
  863. void purple_accounts_remove(PurpleAccount *account);
  864.  
  865. /**
  866.  * Deletes an account.
  867.  *
  868.  * This will remove any buddies from the buddy list that belong to this
  869.  * account, buddy pounces that belong to this account, and will also
  870.  * destroy @a account.
  871.  *
  872.  * @param account The account.
  873.  */
  874. void purple_accounts_delete(PurpleAccount *account);
  875.  
  876. /**
  877.  * Reorders an account.
  878.  *
  879.  * @param account   The account to reorder.
  880.  * @param new_index The new index for the account.
  881.  */
  882. void purple_accounts_reorder(PurpleAccount *account, gint new_index);
  883.  
  884. /**
  885.  * Returns a list of all accounts.
  886.  *
  887.  * @return A list of all accounts.
  888.  */
  889. GList *purple_accounts_get_all(void);
  890.  
  891. /**
  892.  * Returns a list of all enabled accounts
  893.  *
  894.  * @return A list of all enabled accounts. The list is owned
  895.  *         by the caller, and must be g_list_free()d to avoid
  896.  *         leaking the nodes.
  897.  */
  898. GList *purple_accounts_get_all_active(void);
  899.  
  900. /**
  901.  * Finds an account with the specified name and protocol id.
  902.  *
  903.  * @param name     The account username.
  904.  * @param protocol The account protocol ID.
  905.  *
  906.  * @return The account, if found, or @c FALSE otherwise.
  907.  */
  908. PurpleAccount *purple_accounts_find(const char *name, const char *protocol);
  909.  
  910. /**
  911.  * This is called by the core after all subsystems and what
  912.  * not have been initialized.  It sets all enabled accounts
  913.  * to their startup status by signing them on, setting them
  914.  * away, etc.
  915.  *
  916.  * You probably shouldn't call this unless you really know
  917.  * what you're doing.
  918.  */
  919. void purple_accounts_restore_current_statuses(void);
  920.  
  921. /*@}*/
  922.  
  923.  
  924. /**************************************************************************/
  925. /** @name UI Registration Functions                                       */
  926. /**************************************************************************/
  927. /*@{*/
  928. /**
  929.  * Sets the UI operations structure to be used for accounts.
  930.  *
  931.  * @param ops The UI operations structure.
  932.  */
  933. void purple_accounts_set_ui_ops(PurpleAccountUiOps *ops);
  934.  
  935. /**
  936.  * Returns the UI operations structure used for accounts.
  937.  *
  938.  * @return The UI operations structure in use.
  939.  */
  940. PurpleAccountUiOps *purple_accounts_get_ui_ops(void);
  941.  
  942. /*@}*/
  943.  
  944.  
  945. /**************************************************************************/
  946. /** @name Accounts Subsystem                                              */
  947. /**************************************************************************/
  948. /*@{*/
  949.  
  950. /**
  951.  * Returns the accounts subsystem handle.
  952.  *
  953.  * @return The accounts subsystem handle.
  954.  */
  955. void *purple_accounts_get_handle(void);
  956.  
  957. /**
  958.  * Initializes the accounts subsystem.
  959.  */
  960. void purple_accounts_init(void);
  961.  
  962. /**
  963.  * Uninitializes the accounts subsystem.
  964.  */
  965. void purple_accounts_uninit(void);
  966.  
  967. /*@}*/
  968.  
  969. #ifdef __cplusplus
  970. }
  971. #endif
  972.  
  973. #endif /* _PURPLE_ACCOUNT_H_ */
  974.